目次 グリフ情報の取得 グリフアウトラインの取得 グリフメトリックスの取得 データ型リファレンス APIリファレンス ダウンロード

このテクニカルノートは、ATSUI（Apple Type Services for Unicode Imaging）のAPIと概念に精通している方を対象にしています。 ATSUIはUnicodeテキストを描画するためのAppleのAPIです。高レベルのATSUI APIの他に、ATSUIには、低レベルでテキスト情報にアクセス可能なAPIセットも追加されました。これらのAPIには次の関数が含まれます。 - ATSUTextLayoutに対応するグリフとグリフの位置を取得します。各グリフごとに、対応するフォントのグリフ ID、グリフが取り出された元のテキストの文字、グリフの位置情報を調べることができます。 - あるフォントの特定のグリフについて、グリフのアウトラインデータを取得します。これらはグリフの形状を形成する曲線です。 - 特定のフォントの特定のグリフについて、そのグリフの理想（解像度に依存しない）メトリックスとスクリーン（解像度に依存する）メトリックスを取得します。 - ATSUTextLayoutで取得した任意のグリフと位置のセットを、グリフの位置情報を変えるなどした後に描画します。 これは以前Mac OS 9で、特別なTrueTypeスケーラ呼び出し、またはAdobe® Type ManagerによってエクスポートされたAPIへの呼び出しを組み合わせることによって使用できた機能です。これらのいずれのAPIセットも、Mac OS Xのネイティブアプリケーションでは使用できません。これらATSUIの低レベルAPIを呼び出すことによって、TrueTypeとType 1の両方に対して1つのAPIセットを使用でき、お使いのコードをCarbonLibとネイティブMac OS Xの両方で動作させることができます。 [2001年11月26日]

グリフ情報の取得

ATSUTextLayout からグリフ情報を取得するのが、このテクニカルノートで説明するすべての API で最初に行うことです。他のすべての API を呼び出すためには、グリフ情報が必要です。

個々のグリフのプロパティに関する情報が必要ない場合でも、グリフ情報があると描画前にグリフを再配置できます。曲線に沿ってテキストを描画するなど、ATSUI が直接サポートしない方法でもテキストを描画できます。

API 関数 ATSUGetGlyphInfo は、指定する範囲の各グリフについて次の情報を返します。

• グリフに関連付いている ATSUStyle
  
  
• ATSUStyle で指定されたフォントにおけるグリフの ID
  
  
• 対象グリフ文字が対応する文字の元のテキストにおけるオフセット位置
  
  
• グリフのクロスストリームシフト（あれば）
  
  
• グリフが接している直線の先頭からの x オフセット（理想（解像度に依存しない）座標）
  
  
• グリフが接している直線の先頭からの x オフセット（相対画面（解像度に依存する）座標）
  
  
• グリフの先頭キャレットがベースラインと交差する、直線の先頭からの x オフセット（画面（解像度に依存する）座標）
  
  
• 現在 Apple によって予約されている追加フィールドの内容
  
  

ATSUTextLayout の元の Unicode 文字と ATSUGetGlyphInfo によって返されるグリフとの関係が必ずしも 1 対 1 ではなく、場合によってはかなり複雑になるということも頭に入れて置いてください。実際単純なラテン語の文字 é は、e と ´ との組み合わせで表現できます。この場合、2 つの文字は 1 つのグリフにマッピングします。

fi などの一般的なリガチャーもいくつかのフォントでは自動的に形成され、2 文字が 1 つのグリフにマッピングします。アラビア語など右から左へ書く筆記体や Devanagari （タイ語）などの複雑な筆記体の文字からグリフへのマッピングはさらに複雑です。文字とグリフ間で 1 対 1 のマッピングを仮定すると、このような言語で互換性がなくなり、場合によっては欧州の言語や日本語でも互換性がなくなります。

こうした理由のために、可能な場合は高レベルの ATSUI API を使い、ATSUI に一度に段落全体のテキストをレイアウトさせるのが最良の方法です。そうすれば、アプリケーションをこの種の問題から完全に解放できます。

次に示すのは、ATSUTextLayout の最初のグリフに関連付けられているグリフ情報をフェッチするコードの一部です。変更を加えられた可能性のある ATSUGlyphInfoArray を描画する方法を含め API の詳細については、本テクニカルノートの最後の API リファレンスを参照してください。

 
char giaBuffer[128];

 
ByteCount giabc = 128;

ATSUGlyphInfoArray *gia = (ATSUGlyphInfoArray *)giaBuffer;

status = ATSUGetGlyphInfo(atsuLayout, 0, 1, &giabc, gia);

先頭に戻る

グリフアウトラインの取得

グリフ ID とグリフの取り出し元のフォントの両方がわかっていれば、グリフの形状を形成する曲線、すなわちグリフアウトラインを取得できます。ATSUI では、グリフアウトラインの取得に役立つ API をいくつか提供します。これらの API を使うと次のことが可能になります。

• 当該フォントのネイティブ曲線のタイプを知る。TrueType フォントは 2 次曲線を使い、Type 1（PostScript）フォントは 3 次曲線を使います。これには ATSUGetNativeCurveType を使います。
  
  
• グリフの形状を形成する曲線と直線のセグメントごとに呼ばれるコールバック関数を渡すことによって 1 つのグリフの形状を形成する曲線を取得する。
  
  
• TrueType フォントまたは Type 1 フォントから生の 2 次曲線データを取得する（Type 1 の 3 次曲線は、2 次曲線の形式に変換されます）。
  
  

コールバックを使って曲線を取得する API には、ATSUGetQuadraticGlyphPaths と ATSUGetCubicGlyphPaths の 2 つがあります。ネイティブ曲線のタイプが 3 次でも ATSUGetQuadraticGlyphPaths を呼び出せ、ネイティブ曲線のタイプが 2 次でも ATSUGetCubicGlyphPaths を呼び出せます。いずれの場合もフォントの曲線は、求めている形式に変換されます。

2 次パスの取得時に、コールバックは以下を取得するために使用されます。

• 新規パスの始点
  
  
• 始点と終点を与えるパスの各直線
  
  
• 始点、終点、曲線外の制御点を示すパスの各 2 次曲線
  
  
• 現在のオープンパスの終点
  
  

3 次パスの取得時に、コールバックは以下を取得するために使用されます。

• 各ペン位置の新しい場所への移動
  
  
• 現在のペン位置から終わりの位置への各直線
  
  
• 2 つの曲線外の制御点を持つ現在のペン位置から終わりの位置への各曲線
  
  
• 現在のオープンパスの終点
  
  

3 次パスについては、各曲線または直線の開始位置は必ず現在のペン位置からになっていることに注目してください。パスの開始もまた現在のペン位置からになっており、最初の移動が合図になって最初のペン位置を確立します。

また返される曲線は、フォントに存在するヒントによって変更が加えられたものであることにも注目してください。ヒントのないアウトラインが必要な場合は、非常に大きなポイントサイズ（1000 ポイントなど）を使って、その結果として得られる曲線を縮小してください。別の方法としては、ATSUStyle の ATSUStyleRenderngOptions を 0 に設定することもできます。

返される曲線と直線の座標は、y 軸が下向きの QuickDraw 座標です。

詳細については、本テクニカルノートの最後の API リファレンスを参照してください。

先頭に戻る

グリフメトリックスの取得

ATSUI を使って、グリフの理想（解像度に依存しない）メトリックスと画面（解像度に依存する）メトリックスの両方を取得できます。

理想メトリックスについて、ATSUI は次のものを返します。

• グリフのアドバンス（グリフ描画後にペンが進んだ量）。
  
  
• グリフのサイドベアリング。グリフの原点からグリフイメージの始点までのオフセット。
  
  
• グリフのもう一方のサイドベアリング。グリフイメージの終点からグリフのアドバンスの終点までのオフセット。
  
  

画像メトリックスについて、ATSUI は次のものを返します。

• デバイスのアドバンス。実際に画面に描画されるグリフのアドバンスのピクセル数。
  
  
• グリフの左上の点（デバイス座標）。
  
  
• グリフの高さと幅（ピクセル数）。グリフは描画の際、重なることがあります。
  
  
• サイドベアリングともう一方のサイドベアリング（ピクセル数）。
  
  

詳細については、次の API リファレンスを参照してください。

先頭に戻る

データ型リファレンス

データ型と定数

これらの新しい API は、次の定数とデータ[バグ] 型を使用します。

/* ATSUGetNativeCurveType で使用するグリフアウトラインパスの定数 */

enum { kATSCubicCurveType = 0x0001,

       kATSQuadCurveType = 0x0002,

       kATSOtherCurveType = 0x0003

     };

typedef UInt16 GlyphID;

typedef UInt16 ATSCurveType;

struct ATSGlyphIdealMetrics {

        /* API ルーチン ATSGetGlyphIdealMetrics で使用する構造体 */

        Float32Point advance;

        Float32Point sideBearing;

        Float32Point otherSideBearing;

        };

struct ATSGlyphScreenMetrics {

        /* API ルーチン ATSGetGlyphScreenMetrics で使用する構造体 */

        Float32Point deviceAdvance;

        Float32Point topLeft;

        UInt32 height;

        UInt32 width;

        Float32Point sideBearing;

        Float32Point otherSideBearing;

        };

ATSUGetQuadraticGlyphPaths のコールバック

2 次曲線において、pt1 は開始点、pt2 は終点、controlPt は曲線外の制御点です。「TrueType Reference Manualの第 1 章」では、それぞれ p0、p2、p1 となっています。曲線と直線の両方において、開始点は明示的にコールバック関数へ渡されます。移動は暗黙で、MoveTo コールバックはありません。

typedef CALLBACK_API( OSStatus , ATSQuadraticNewPathProcPtr )

    (void *callBackDataPtr);

typedef CALLBACK_API( OSStatus , ATSQuadraticLineProcPtr )

    (const Float32Point *pt1, const Float32Point *pt2, void *callBackDataPtr);

typedef CALLBACK_API( OSStatus , ATSQuadraticCurveProcPtr )

    (const Float32Point *pt1, const Float32Point *controlPt,

     const Float32Point *pt2, void *callBackDataPtr);

typedef CALLBACK_API( OSStatus , ATSQuadraticClosePathProcPtr )

    (void *callBackDataPtr);

ATSUGetCubicGlyphPaths コールバック

3 次曲線において、これらの点は『PostScript Language Reference Manual（邦題：PostScript リファレンスマニュアル）』などで定義されています。p0 は開始点で、必ず現在のペン位置になっています。p3 は終点で、p1 と p2 は曲線外の制御点です。曲線と直線の両方において、開始点は暗黙に設定され、ペンを移動するための明示的な MoveTo コールバックがあります。反対に、3 次の場合の NewPath コールバックはありません。

typedef CALLBACK_API( OSStatus , ATSCubicMoveToProcPtr )

    (const Float32Point *pt, void *callBackDataPtr);

typedef CALLBACK_API( OSStatus , ATSCubicLineToProcPtr )

    (const Float32Point *pt, void *callBackDataPtr);

typedef CALLBACK_API( OSStatus , ATSCubicCurveToProcPtr )

    (const Float32Point *pt1, const Float32Point *pt2,

     const Float32Point *pt3, void *callBackDataPtr);

typedef CALLBACK_API( OSStatus , ATSCubicClosePathProcPtr )

    (void *callBackDataPtr);



struct Float32Point {

    Float32 x;

    Float32 y;

};

次のデータ構造体は、グリフアウトラインを返すために使用されます。このデータの形式は、TrueType フォントのグリフテーブル内で定義されているものと同じです。これについては、「TrueType Reference Manual の第 6 章」で解説されています。このデータは、次の通り呼び出し元に返される前に変更が加えられ、制御ビットは long 型の整数倍になるようにパディングされ、座標値は固定小数点から浮動小数点に変換されます。詳細は、『TrueType reference manual』を参照してください。

struct ATSUCurvePath {

    UInt32 vectors;

    UInt32 controlBits[1];

    Float32Point vector[1];

};

 
struct ATSUCurvePaths {

    UInt32 contours;

    ATSUCurvePath contour[1];

};

次のデータ構造体は ATSUTextLayout に関連付けられているグリフ情報を返すために使用します。各グリフについて、次の情報が返されます。16 ビットのグリフ識別子（対応するフォントに対して一意）、予約済みフィールド「reserved」と「layoutFlags」、グリフの取り出し元となる対応する Unicode 文字ストリームにおける文字インデックス、グリフで使用される ATSUStyle、グリフの任意のクロスストリームシフト、レイアウトの原点からの理想ストリームオフセット、レイアウトの原点からのデバイス調整後のストリームオフセット、グリフのトレーリングキャレットがベースラインと交差するデバイス座標値。

struct ATSUGlyphInfo {

    GlyphID glyphID;

    UInt16 reserved;

    UInt32 layoutFlags;

    UniCharArrayOffset charIndex;

    ATSUStyle style;

    Float32 deltaY;

    Float32 idealX;

    SInt16 screenX;

    SInt16 caretX;

};



struct ATSUGlyphInfoArray {

    ItemCount numGlyphs;

    ATSUTextLayout layout;

    ATSUGlyphInfo glyphs[1];

};

先頭に戻る

API リファレンス

メトリックス

ATSUGlyphGetIdealMetrics

OSStatus ATSUGlyphGetIdealMetrics (

    ATSUStyle iATSUStyle,

    ItemCount iNumOfGlyphs,

    GlyphID * iGlyphIDs,

    Sint32 iInputOffset,

    ATSGlyphIdealMetrics * oIdealMetrics );

この関数は、入力 glyphID の配列と ATSUStyle によって指定されるグリフの理想メトリックスを取得するために使用します。理想メトリックスは、グリフのアウトライン、フォント、ポイントサイズ、垂直などのスタイル属性から取得されます。1 つのスタイルランしか渡すことができないので、最大でも呼び出しごとに 1 つのスタイルしか処理できません。oIdealMetrics は、要求された数のメトリックスを格納するために、呼び出し元によって事前に割り当てらていなければなりません。

垂直メトリックスが必要な場合は、ATSUStyle で kATSUVerticalCharacterTag を設定します。

入力パラメータ

出力パラメータ

戻り値

ATSUGetNativeCurveType

OSStatus ATSUGetNativeCurveType(

    ATSUStyle iATSUStyle,

    CurveType * oCurveType);

この関数は、ATSUStyle によって参照されるネイティブ曲線タイプ（3 次または 2 次）を取得するのに使用します。

入力パラメータ

出力パラメータ

グリフのパス

ATSUGlyphGetCubicPaths と ATSUGlyphGetQuadraticPaths

OSStatus ATSUGlyphGetCubicPaths(

ATSUStyle iATSUStyle,

GlyphID iGlyphID,

ATSCubicMoveToUPP iMoveToProc,

ATSCubicLineToUPP iLineToProc,

ATSCubicCurveToUPP iCurveToProc,

ATSCubicClosePathUPP iClosePathProc,

void *iCallBackDataPtr,

OSStatus *oCallBackResult);

この関数は、コールバック関数を利用して 1 つのグリフの 3 次アウトラインパスを返します。返されたこのアウトラインは指定されたサイズでのヒント付きのアウトラインです。ヒントなしのアウトラインの効果を得るには、非常に大きいサイズ（たとえば 1000 ポイント）を要求し、曲線を希望のサイズまで縮小します。

いくつかのフォントはグリフパスへのアクセスを制限しています。その場合、ATSUGlyphGetCubicPaths はエラーコード kATSNotPublicOutlinesErr を返します。

入力パラメータ

出力パラメータ

戻り値

OSStatus ATSUGlyphGetQuadraticPaths(

    ATSUStyle iATSUStyle,

    GlyphID iGlyphID,

    ATSQuadraticNewPathUPP iNewPathProc,

    ATSQuadraticLineUPP iLineToProc,

    ATSQuadraticCurveUPP iCurveToProc,

    ATSQuadraticClosePathUPP iClosePathProc,

    void *iCallBackDataPtr,

    OSStatus *oCallBackResult);

この関数は、コールバック関数を利用して 1 つのグリフの 2 次アウトラインパスを返します。返されたこのアウトラインは指定されたサイズでのヒント付きのアウトラインです。ヒントなしのアウトラインの効果を得るには、非常に大きいサイズ（たとえば 1000 ポイント）を要求し、曲線を希望のサイズまで縮小します。

いくつかのフォントはグリフパスへのアクセスを制限しています。その場合、ATSGlyphGetQuadraticPaths はエラーコード kATSNotPublicOutlinesErr を返します。

入力パラメータ

出力パラメータ

戻り値

ATSUGlyphGetCurvePaths

OSStatus ATSUGlyphGetCurvePaths (

    ATSUStyle iATSUStyle,

    GlyphID iGlyphID,

    ByteCount *ioBufferSize,

    ATSUCurvePaths *oPaths);

この関数は、データ構造体を利用して 1 つのグリフのアウトラインパスを返します。返されたこのアウトラインは指定されたサイズでのヒント付きのアウトラインです。ヒントなしのアウトラインの効果を得るには、非常に大きいサイズ（たとえば 1000 ポイント）を要求し、曲線を希望のサイズまで縮小します。

この関数は、2 次パスのみ返します。Apple では、可能な限りコールバック API の ATSUGlyphGetCubicPaths と ATSUGlyphGetQuadraticPaths を使うことをお勧めします。

いくつかのフォントはグリフパスへのアクセスを制限しています。その場合、ATSUGetCurvePaths はエラーコード kATSNotPublicOutlinesErr と oPaths に対して NULL を返します。

入力パラメータ

戻り値

グリフデータアクセス

ATSUGetGlyphInfo

OSStatus ATSUGetGlyphInfo(

    ATSUTextLayout iTextLayout,

    UniCharArrayOffset iLineStart,

    UniCharCount iLineLength,

    ByteCount *ioBufferSize,

    ATSGlyphInfoArray *oGlyphInfoPtr );

この関数は、ATSUTextLayout からグリフ情報を返します。このデータは ATSUI が使用する内部情報のコピーで、変更を加えることができます。ただし、ATSUIDrawGlyphInfo を呼び出すときにこの ATSGlyphInfoArray を使う場合は、deltaY、idealX、screenX、caretX 以外の情報を変更すると、描画する際に動作は不定となります。

グリフ情報での作業が終了するまでは、返されたグリフ情報に対応する ATSUTextLayout を変更、または削除してはなりません。

入力パラメータ

戻り値

ATSUDrawGlyphInfo

OSStatus ATSUDrawGlyphInfo(

    ATSGlyphInfoArray *iGlyphInfoArray,

    Float32Point iLocation);

この関数は、ATSGlyphInfoArray のグリフを描画するために使用します。呼び出し元が、deltaY、idealX、screenX、caretX 以外の iGlyphInfoArray のデータを修正すると、結果は不定となります。

入力パラメータ

戻り値

デバイス固有のルーチン

ATSUGlyphGetScreenMetrics

OSStatus ATSUGlyphGetScreenMetrics (

    ATSUStyle iATSUStyle,

    ItemCount iNumOfGlyphs,

    GlyphID * iGlyphIDs,

    Sint32 iInputOffset,

    ATSGlyphScreenMetrics * oScreenMetrics );

この関数は、入力 glyphIDs と ATSUStyle で指定されたグリフの画面メトリックスを取得するために使用します。画面メトリックスは、アンチエイリアシングがスタイルのポイントサイズ、スタイル変換、その他のスタイル属性に設定されていても、現在の QuickDraw grafPort の解像度とビットデプスを基に指定されたスタイルのフォントスケーラーの算出結果から取り出されます。1 つのスタイル入力しかないので、各呼び出しで 1 つのスタイルランしか測定できません。

画面メトリックスはピクセル単位で作業しなければならないときに役に立ちます。たとえば、あるグリフが何ピクセルで構成されているかを正確に知りたいときなどに便利です。

oScreenMetrics は、要求された数のメトリックスを格納するために、呼び出し元によって事前に割り当てられている必要があります。

入力パラメータ

出力パラメータ

戻り値

先頭に戻る